Summary

Merge the current main-target PR set through a single verified release branch.

Included PRs: #140 #141 #149 #263 #298 #299 #300 #302 #303 #304 #306 #307 #308 #309

Additional release fixes

• fix optional dashboard display dependency in forecast command tests
• tighten backend settings schema max for sessionAffinityMaxEntries
• treat EACCES as retryable for queued settings writes
• fix docs parity coverage for extracted switch command docs
• correct backup metadata latest-valid-path selection priority
• add storage regressions around named-backup export snapshot isolation

Local validation

• npm run clean:repo:check
• npm run typecheck
• npm run build
• npm run lint
• npm test -- test/storage.test.ts test/named-backup-export.test.ts test/storage-recovery-paths.test.ts test/backup-metadata-builder.test.ts
• npx vitest run --maxWorkers=1 --silent --shard=1/4
• npx vitest run --maxWorkers=1 --silent --shard=2/4
• npx vitest run --maxWorkers=1 --silent --shard=1/8
• npx vitest run --maxWorkers=1 --silent --shard=2/8
• npx vitest run --maxWorkers=1 --silent --shard=3/8
• npx vitest run --maxWorkers=1 --silent --shard=4/8
• npx vitest run --maxWorkers=1 --silent --shard=5/8

Known local blocker

• larger remaining Vitest shard runs hit a local worker OOM before any concrete failing assertion was identified; this PR exists to get the authoritative Ubuntu/Node CI result on the combined release state before merging to main.

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

large release branch merging 14 prs. core areas touched: session-affinity gets lastResponseId threading for response continuation; named-backup-export fixes a real concurrency race (in-flight guard now set before first await); backup-metadata-builder introduces correct priority-ordered snapshot selection; import-export fixes the previously flagged negative importedCount bug; settings-write-queue adds EACCES to retryable codes (helpful on windows, mild false-positive on linux); the codex-manager surface is heavily refactored into focused sub-modules.

• prior review concern (proactiveRefreshGuardian/proactiveRefreshIntervalMs unreachable in UI) is resolved — both are now in the refresh-recovery category
• prior review concern (importedCount going negative) is resolved — mergeImportedAccounts now deduplicates existing accounts before computing the delta
• rememberLastResponseId is a zero-value wrapper around updateLastResponseId; the jsdoc references a non-existent rememberWithResponseId upsert method — clean up or implement the referenced method
• sessionAffinityMaxEntries zod schema lacks .max(4_096) to match the ui cap, so direct config edits can grow the in-memory map unboundedly
• EACCES in RETRYABLE_SETTINGS_WRITE_CODES is correct for windows file locks but adds ~800ms of wasted retry time on linux/macOS for true permission-denied errors

Confidence Score: 4/5

• safe to merge after addressing the missing .max() on sessionAffinityMaxEntries and the dangling rememberWithResponseId jsdoc reference
• both previously flagged correctness issues are resolved; the three remaining comments are p2 style/hardening items — none block the primary user path or introduce data loss risk. the concurrency race in named-backup-export is properly fixed. the oom-blocked vitest shards are a local resource constraint, not a code defect.
• lib/schemas.ts (missing max bound), lib/session-affinity.ts (redundant public method + dangling jsdoc), lib/codex-manager/settings-write-queue.ts (EACCES on non-windows)

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant Caller
    participant SessionAffinityStore
    participant EntriesMap

    Note over Caller,EntriesMap: response continuation flow (new)
    Caller->>SessionAffinityStore: remember(sessionKey, accountIndex, now)
    SessionAffinityStore->>EntriesMap: get(key) → existingEntry (preserve lastResponseId)
    SessionAffinityStore->>SessionAffinityStore: setEntry(key, {accountIndex, lastResponseId: existing})
    SessionAffinityStore->>EntriesMap: evict oldest if at maxEntries, then set

    Caller->>SessionAffinityStore: updateLastResponseId(sessionKey, responseId, now)
    SessionAffinityStore->>EntriesMap: get(key) → entry
    alt entry missing or expired
        SessionAffinityStore-->>Caller: no-op (delete if expired)
    else entry live
        SessionAffinityStore->>SessionAffinityStore: setEntry(key, {...entry, lastResponseId, expiresAt refreshed})
        SessionAffinityStore-->>Caller: void
    end

    Caller->>SessionAffinityStore: getLastResponseId(sessionKey, now)
    SessionAffinityStore->>EntriesMap: get(key)
    alt expired
        SessionAffinityStore->>EntriesMap: delete(key)
        SessionAffinityStore-->>Caller: null
    else live
        SessionAffinityStore-->>Caller: lastResponseId (trimmed) or null
    end

This is a comment left during a code review.
Path: lib/session-affinity.ts
Line: 95-107

Comment:
**`rememberLastResponseId` is a dead-alias wrapper with a dangling JSDoc reference**

`rememberLastResponseId` is a one-line forwarding shell for `updateLastResponseId` and adds no behaviour on top of it. the jsdoc says callers that need to upsert continuation state should use `rememberWithResponseId`, but that method does not exist anywhere in the codebase — so the comment actively misleads future engineers looking for an upsert path.

either drop the wrapper and have callers use `updateLastResponseId` directly, or implement the missing `rememberWithResponseId` upsert method and point the jsdoc at it correctly. leaving two identical public methods increases the surface for concurrency confusion if one ever diverges.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: lib/schemas.ts
Line: 49

Comment:
**`sessionAffinityMaxEntries` Zod schema missing `.max()` bound**

the pr description says "tighten backend settings schema max for `sessionAffinityMaxEntries`", and the UI control in `backend-settings-schema.ts` correctly caps the value at `4_096`. however the Zod schema here has no corresponding `.max()` — a user editing the config JSON directly can set an arbitrarily large value (e.g. `1_000_000`) and it will pass validation, growing the in-memory `Map` unboundedly. the `SessionAffinityStore` constructor only floors via `Math.max(1, …)`, so no runtime guard catches it.

```suggestion
	sessionAffinityMaxEntries: z.number().min(8).max(4_096).optional(),
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: lib/codex-manager/settings-write-queue.ts
Line: 8

Comment:
**`EACCES` is not transient on linux/macOS — consider scoping to windows**

`EACCES` (permission denied) is included as a retryable code. on windows this can be a transient file-lock, which is the intent. on linux/macOS `EACCES` is a hard permission denial that will not resolve on retry, so all 4 attempts will fail and callers receive the error ~800ms later than expected. consider noting this in a comment, or gating on `process.platform === "win32"` for `EACCES` specifically to avoid silent slowdowns on posix hosts when account-storage permissions are actually wrong.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (3): Last reviewed commit: "Fix release branch review follow-ups" | Re-trigger Greptile}